Clover icon

compiler

  1. Project Clover database Mon Jan 2 2023 15:09:37 MST
  2. Package com.google.javascript.jscomp

File CodingConvention.java

 

Coverage histogram

../../../../img/srcFileCovDistChart10.png
0% of files have more coverage

Code metrics

4
21
10
7
414
129
12
0.57
2.1
1.43
1.2

Classes

Class Line # Actions
CodingConvention 36 0 0 0
-1.0 -
CodingConvention.Bind 257 7 3 0
1.0100%
CodingConvention.SubclassType 315 0 0 0
-1.0 -
CodingConvention.SubclassRelationship 320 3 1 0
1.0100%
CodingConvention.DelegateRelationship 339 2 1 3
0.00%
CodingConvention.ObjectLiteralCast 356 3 1 0
1.0100%
CodingConvention.AssertionFunctionSpec 379 6 6 0
1.0100%
 

Contributing tests

This file is covered by 6649 tests. .

Source view

1    /*
2    * Copyright 2007 The Closure Compiler Authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10    * Unless required by applicable law or agreed to in writing, software
11    * distributed under the License is distributed on an "AS IS" BASIS,
12    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13    * See the License for the specific language governing permissions and
14    * limitations under the License.
15    */
16    package com.google.javascript.jscomp;
17   
18    import com.google.javascript.rhino.Node;
19    import com.google.javascript.rhino.jstype.FunctionType;
20    import com.google.javascript.rhino.jstype.JSType;
21    import com.google.javascript.rhino.jstype.JSTypeNative;
22    import com.google.javascript.rhino.jstype.JSTypeRegistry;
23    import com.google.javascript.rhino.jstype.ObjectType;
24    import com.google.javascript.rhino.jstype.StaticScope;
25   
26    import java.io.Serializable;
27    import java.util.Collection;
28    import java.util.List;
29    import java.util.Map;
30   
31    /**
32    * CodingConvention defines a set of hooks to customize the behavior of the
33    * Compiler for a specific team/company.
34    *
35    */
 
36    public interface CodingConvention extends Serializable {
37   
38    /**
39    * This checks whether a given variable name, such as a name in all-caps
40    * should be treated as if it had the @const annotation.
41    *
42    * @param variableName potentially constant variable name
43    * @return {@code true} if the name should be treated as a constant.
44    */
45    public boolean isConstant(String variableName);
46   
47    /**
48    * This checks whether a given key of an object literal, such as a
49    * name in all-caps should be treated as if it had the @const
50    * annotation.
51    */
52    public boolean isConstantKey(String keyName);
53   
54    /**
55    * This checks that a given {@code key} may be used as a key for an enum.
56    *
57    * @param key the potential key to an enum
58    * @return {@code true} if the {@code key} may be used as an enum key,
59    * {@code false} otherwise
60    */
61    public boolean isValidEnumKey(String key);
62   
63    /**
64    * This checks whether a given parameter name should be treated as an
65    * optional parameter as far as type checking or function call arg count
66    * checking is concerned. Note that an optional function parameter may be
67    * declared as a simple type and is automatically converted to a union of the
68    * declared type and Undefined.
69    *
70    * @param parameter The parameter's node.
71    * @return {@code true} if the parameter should be treated as an optional
72    * parameter.
73    */
74    public boolean isOptionalParameter(Node parameter);
75   
76    /**
77    * This checks whether a given parameter should be treated as a marker
78    * for a variable argument list function. A VarArgs parameter must be the
79    * last parameter in a function declaration.
80    *
81    * @param parameter The parameter's node.
82    * @return {@code true} if the parameter should be treated as a variable
83    * length parameter.
84    */
85    public boolean isVarArgsParameter(Node parameter);
86   
87    /**
88    * Checks whether a global variable or function name should be treated as
89    * exported, or externally referenceable.
90    *
91    * @param name A global variable or function name.
92    * @param local {@code true} if the name is a local variable.
93    * @return {@code true} if the name should be considered exported.
94    */
95    public boolean isExported(String name, boolean local);
96   
97    /**
98    * Should be isExported(name, true) || isExported(name, false);
99    */
100    public boolean isExported(String name);
101   
102    /**
103    * Checks whether a name should be considered private. Private global
104    * variables and functions can only be referenced within the source file in
105    * which they are declared. Private properties and methods should only be
106    * accessed by the class that defines them.
107    *
108    * @param name The name of a global variable or function, or a method or
109    * property.
110    * @return {@code true} if the name should be considered private.
111    */
112    public boolean isPrivate(String name);
113   
114    /**
115    * Checks if the given method defines a subclass relationship,
116    * and if it does, returns information on that relationship. By default,
117    * always returns null. Meant to be overridden by subclasses.
118    *
119    * @param callNode A CALL node.
120    */
121    public SubclassRelationship getClassesDefinedByCall(Node callNode);
122   
123    /**
124    * Returns true if passed a string referring to the superclass. The string
125    * will usually be from the string node at the right of a GETPROP, e.g.
126    * this.superClass_.
127    */
128    public boolean isSuperClassReference(String propertyName);
129   
130    /**
131    * Convenience method for determining provided dependencies amongst different
132    * JS scripts.
133    */
134    public String extractClassNameIfProvide(Node node, Node parent);
135   
136    /**
137    * Convenience method for determining required dependencies amongst different
138    * JS scripts.
139    */
140    public String extractClassNameIfRequire(Node node, Node parent);
141   
142    /**
143    * Function name used when exporting properties.
144    * Signature: fn(object, publicName, symbol).
145    * @return function name.
146    */
147    public String getExportPropertyFunction();
148   
149    /**
150    * Function name used when exporting symbols.
151    * Signature: fn(publicPath, object).
152    * @return function name.
153    */
154    public String getExportSymbolFunction();
155   
156    /**
157    * Checks if the given CALL node is forward-declaring any types,
158    * and returns the name of the types if it is.
159    */
160    public List<String> identifyTypeDeclarationCall(Node n);
161   
162    /**
163    * In many JS libraries, the function that produces inheritance also
164    * adds properties to the superclass and/or subclass.
165    */
166    public void applySubclassRelationship(FunctionType parentCtor,
167    FunctionType childCtor, SubclassType type);
168   
169    /**
170    * Function name for abstract methods. An abstract method can be assigned to
171    * an interface method instead of an function expression in order to avoid
172    * linter warnings produced by assigning a function without a return value
173    * where a return value is expected.
174    * @return function name.
175    */
176    public String getAbstractMethodName();
177   
178    /**
179    * Checks if the given method defines a singleton getter, and if it does,
180    * returns the name of the class with the singleton getter. By default, always
181    * returns null. Meant to be overridden by subclasses.
182    *
183    * addSingletonGetter needs a coding convention because in the general case,
184    * it can't be inlined. The function inliner sees that it creates an alias
185    * to the given class in an inner closure, and bails out.
186    *
187    * @param callNode A CALL node.
188    */
189    public String getSingletonGetterClassName(Node callNode);
190   
191    /**
192    * In many JS libraries, the function that adds a singleton getter to a class
193    * adds properties to the class.
194    */
195    public void applySingletonGetter(FunctionType functionType,
196    FunctionType getterType, ObjectType objectType);
197   
198    /**
199    * @return Whether the function is inlinable by convention.
200    */
201    public boolean isInlinableFunction(Node n);
202   
203    /**
204    * @return the delegate relationship created by the call or null.
205    */
206    public DelegateRelationship getDelegateRelationship(Node callNode);
207   
208    /**
209    * In many JS libraries, the function that creates a delegate relationship
210    * also adds properties to the delegator and delegate base.
211    */
212    public void applyDelegateRelationship(
213    ObjectType delegateSuperclass, ObjectType delegateBase,
214    ObjectType delegator, FunctionType delegateProxy,
215    FunctionType findDelegate);
216   
217    /**
218    * @return the name of the delegate superclass.
219    */
220    public String getDelegateSuperclassName();
221   
222    /**
223    * Checks for function calls that set the calling conventions on delegate
224    * methods.
225    */
226    public void checkForCallingConventionDefiningCalls(
227    Node n, Map<String, String> delegateCallingConventions);
228   
229    /**
230    * Defines the delegate proxy prototype properties. Their types depend on
231    * properties of the delegate base methods.
232    *
233    * @param delegateProxyPrototypes List of delegate proxy prototypes.
234    */
235    public void defineDelegateProxyPrototypeProperties(
236    JSTypeRegistry registry, StaticScope<JSType> scope,
237    List<ObjectType> delegateProxyPrototypes,
238    Map<String, String> delegateCallingConventions);
239   
240    /**
241    * Gets the name of the global object.
242    */
243    public String getGlobalObject();
244   
245    /**
246    * A Bind instance or null.
247    */
248    public Bind describeFunctionBind(Node n);
249   
250    /**
251    * A Bind instance or null.
252    * @param useTypeInfo If we believe type information is reliable enough
253    * to use to figure out what the bind function is.
254    */
255    public Bind describeFunctionBind(Node n, boolean useTypeInfo);
256   
 
257    public static class Bind {
258    // The target of the bind action
259    final Node target;
260    // The node representing the "this" value, maybe null
261    final Node thisValue;
262    // The head of a Node list representing the parameters
263    final Node parameters;
264   
 
265  162 toggle public Bind(Node target, Node thisValue, Node parameters) {
266  162 this.target = target;
267  162 this.thisValue = thisValue;
268  162 this.parameters = parameters;
269    }
270   
271    /**
272    * The number of parameters bound (not including the 'this' value).
273    */
 
274  20 toggle int getBoundParameterCount() {
275  20 if (parameters == null) {
276  6 return 0;
277    }
278  14 Node paramParent = parameters.getParent();
279  14 return paramParent.getChildCount() -
280    paramParent.getIndexOfChild(parameters);
281    }
282    }
283   
284    /**
285    * Whether this CALL function is testing for the existence of a property.
286    */
287    public boolean isPropertyTestFunction(Node call);
288   
289    /**
290    * Whether this GETPROP node is an alias for an object prototype.
291    */
292    public boolean isPrototypeAlias(Node getProp);
293   
294    /**
295    * Checks if the given method performs a object literal cast, and if it does,
296    * returns information on the cast. By default, always returns null. Meant
297    * to be overridden by subclasses.
298    *
299    * @param callNode A CALL node.
300    */
301    public ObjectLiteralCast getObjectLiteralCast(Node callNode);
302   
303    /**
304    * Gets a collection of all properties that are defined indirectly on global
305    * objects. (For example, Closure defines superClass_ in the goog.inherits
306    * call).
307    */
308    public Collection<String> getIndirectlyDeclaredProperties();
309   
310    /**
311    * Returns the set of AssertionFunction.
312    */
313    public Collection<AssertionFunctionSpec> getAssertionFunctions();
314   
 
315    static enum SubclassType {
316    INHERITS,
317    MIXIN
318    }
319   
 
320    static class SubclassRelationship {
321    final SubclassType type;
322    final String subclassName;
323    final String superclassName;
324   
 
325  659 toggle public SubclassRelationship(SubclassType type,
326    Node subclassNode, Node superclassNode) {
327  659 this.type = type;
328  659 this.subclassName = subclassNode.getQualifiedName();
329  659 this.superclassName = superclassNode.getQualifiedName();
330    }
331    }
332   
333    /**
334    * Delegates provides a mechanism and structure for identifying where classes
335    * can call out to optional code to augment their functionality. The optional
336    * code is isolated from the base code through the use of a subclass in the
337    * optional code derived from the delegate class in the base code.
338    */
 
339    static class DelegateRelationship {
340    /** The subclass in the base code. */
341    final String delegateBase;
342   
343    /** The class in the base code. */
344    final String delegator;
345   
 
346  0 toggle DelegateRelationship(String delegateBase, String delegator) {
347  0 this.delegateBase = delegateBase;
348  0 this.delegator = delegator;
349    }
350    }
351   
352    /**
353    * An object literal cast provides a mechanism to cast object literals to
354    * other types without a warning.
355    */
 
356    static class ObjectLiteralCast {
357    /** Type to cast to. */
358    final String typeName;
359   
360    /** Object to cast. */
361    final Node objectNode;
362   
363    /** Error message */
364    final DiagnosticType diagnosticType;
365   
 
366  19 toggle ObjectLiteralCast(String typeName, Node objectNode,
367    DiagnosticType diagnosticType) {
368  19 this.typeName = typeName;
369  19 this.objectNode = objectNode;
370  19 this.diagnosticType = diagnosticType;
371    }
372    }
373   
374    /**
375    * A function that will throw an exception when either:
376    * -One or more of its parameters evaluate to false.
377    * -One or more of its parameters are not of a certain type.
378    */
 
379    public class AssertionFunctionSpec {
380    protected final String functionName;
381    protected final JSTypeNative assertedType;
382   
 
383  7056 toggle public AssertionFunctionSpec(String functionName) {
384  7056 this(functionName, null);
385    }
386   
 
387  49392 toggle public AssertionFunctionSpec(String functionName,
388    JSTypeNative assertedType) {
389  49392 this.functionName = functionName;
390  49392 this.assertedType = assertedType;
391    }
392   
393    /** Returns the name of the function. */
 
394  49392 toggle public String getFunctionName() {
395  49392 return functionName;
396    }
397   
398    /**
399    * Returns the parameter of the assertion function that is being checked.
400    * @param firstParam The first parameter of the function call.
401    */
 
402  66 toggle public Node getAssertedParam(Node firstParam) {
403  66 return firstParam;
404    }
405   
406    /**
407    * Returns the type for a type assertion, or null if the function asserts
408    * that the node must not be null or undefined.
409    */
 
410  58 toggle public JSType getAssertedType(Node call, JSTypeRegistry registry) {
411  58 return assertedType != null ? registry.getNativeType(assertedType) : null;
412    }
413    }
414    }